Add directions to playbook for Science Pipelines quick-builds #242
Conversation
eigerx
force-pushed
the
tickets/DM-48010
branch
2 times, most recently
from
3bfca5b to
e7c15e0
Compare
eigerx
force-pushed
the
tickets/DM-48010
branch
from
1bc104b to
62e1136
Compare
There was a problem hiding this comment.
Thanks for the updates (especially the list format, which I didn't know how to do)! However, aside from my question of whether the quick-stack instructions belong here at all, I think some of the details have gotten mixed up. I'd like to see those resolved before I approve.
| @@ -67,6 +67,36 @@ Any subsequent builds of the service container will build against both bases. | |||
|
|
|||
| This is the only situation in which a change to ``BASE_TAG_LIST`` should be committed to ``main``. | |||
|
|
|||
| In case your intended Base Container is not a tagged Science Pipelines Release: Building the Science Pipelines Manually | |||
| ----------------------------------------------------------------------------------------------------------------------- | |||
| It will sometimes be necessary to compile a container with the LSST Science Pipelines manually. Generally, this only occurs if the intended daily or weekly stack does not compile. In these cases, the Science Pipelines themselves must be built ahead of the base container. Here are instructions for building the Science Pipelines. | |||
There was a problem hiding this comment.
It seems to me that, since this is not Prompt Processing functionality, it should be documented elsewhere (https://github.com/lsst/gha_build/?) and merely linked from here. That would keep our documentation focused (see DMTN-030), and would make the build documentation visible to other users of the quick-stack system.
There was a problem hiding this comment.
Please write (at most) one sentence per line, per the dev guide. That makes for much cleaner diffs in future editing; otherwise, changing one word might be treated as a rewrite of an entire paragraph!
|
|
||
| #. Check the `Science Pipelines changelog <https://lsst-dm.github.io/lsst_git_changelog/weekly/>`_ to make sure only the intended changes are on ``main``. | ||
|
|
||
| If ``main`` contains only changes that are intended for the Science Pipelines build, proceed and build the main branch! Otherwise, a cherry-pick or backport branch should be built. |
There was a problem hiding this comment.
Given my next comment, I assume this is actually backport branches in each Science Pipelines package with changes of interest. If this is correct, please say so.
|
|
||
| #. **Use workflow from** | ||
|
|
||
| In almost all cases, you'll want the ``main`` branch. Generally speaking, this is the branch of the Science Pipelines that you're trying to build. If there is a specific branch for a cherry-pick or backport, you'll want that branch instead. |
There was a problem hiding this comment.
I think this is conflating "Use workflow from" (which I agree you usually don't want to touch) and "List of refs to build" (where I would expect to almost always see backport branches).
There was a problem hiding this comment.
More a style question, but... why use ordered (numbered) lists instead of unordered lists for fields? They all appear together on the same form. Same question for the reformatting of the PP workflow later.
|
|
||
| #. **List of products to build** | ||
|
|
||
| Insert products to build, just like for Jenkins, but the default is what the standard containers have (except ``pipelines_check``). |
There was a problem hiding this comment.
I see only lsst_distrib lsst_sitcom, and not pipelines_check?
| @@ -67,6 +67,36 @@ Any subsequent builds of the service container will build against both bases. | |||
|
|
|||
| This is the only situation in which a change to ``BASE_TAG_LIST`` should be committed to ``main``. | |||
|
|
|||
| In case your intended Base Container is not a tagged Science Pipelines Release: Building the Science Pipelines Manually | |||
There was a problem hiding this comment.
Could this be shortened to "Building the Science Pipelines Manually"? The current title wraps rather awkwardly on my browser.
Or maybe "Using the Quick-Stack Build", since that's almost universally what we call it elsewhere and what a new user would be looking for?
| In the future, there may be "patched weekly" builds, which would justify a patch version of Prompt Processing. | ||
| If you are planning to update the Science Pipelines tag, you should also check the `Science Pipelines changelog <https://lsst-dm.github.io/lsst_git_changelog/weekly/>`_. | ||
| In practice, almost any Science Pipelines update is at least a minor version, because new features are added constantly. | ||
| In the future, there may be "patched weekly" builds, which would justify a patch version of Prompt Processing. |
There was a problem hiding this comment.
I could swear we removed this line, but now it should probably refer to quick-stack.
doc/playbook.rst
Outdated
| 3. Tag the release | ||
| #. Tag the release | ||
|
|
||
| At the HEAD of the ``main`` branch, create and push a tag with the semantic version: | ||
| At the HEAD of the ``main`` branch, create and push a tag with the semantic version: | ||
|
|
||
| .. code-block:: sh | ||
| .. code-block:: sh | ||
|
|
||
| git tag -s X.Y.Z -m "X.Y.Z" | ||
| git push --tags | ||
| git tag -s X.Y.Z -m "X.Y.Z" | ||
| git push --tags |
There was a problem hiding this comment.
I'd recommend removing the step 3 block entirely, as it's confused every newcomer to the build process.
| * New service containers built from ``main`` have the tags of their base container. | ||
| Containers built from a branch are prefixed by the ticket number or, for user branches, the branch topic. | ||
| Containers built from a branch should be prefixed by the ticket number or, for user branches, the branch topic. |
There was a problem hiding this comment.
I don't understand this rewording. Have you seen cases where this doesn't happen (if so, that's a bug in the script)?
| **Guidance on designating major releases:** | ||
|
|
There was a problem hiding this comment.
I can see what you're trying to do, but I think this header would just be more confusing to someone who isn't trying to make a major release. The root problem is that, with the various additions, our actual versioning policy ("Release tags are semantic version identifiers following the pep 440 specification") has moved too far away from the description of the decision-making rules (they're not just guidelines -- compatibility is serious business!)
I think the best solution is to rearrange the existing text (and, if it still needs a header, make it something more generic like "Release types"). There's a lot of interdependency, though; my best idea so far is to move the compatibility rules/API definition out of the list entirely (to right after we say we use semantic versioning), and have item 1 focus entirely on the mechanics of tracking changes. What do you think?
| * If there are no changes (typically because you want to use an updated Science Pipelines container), go to the repository's `Actions tab <https://github.com/lsst-dm/prompt_processing/actions/workflows/build-base.yml>`_ and select "**Run workflow**". From the dropdown menu, select: | ||
|
|
||
| #. The branch whose container definition will be used | ||
| #. The label of the Science Pipelines container. |
There was a problem hiding this comment.
I think you need to include an entry for the science pipelines container (possibly adding it on commit "Add directions to playbook..."?) AFAICT that's the step you and Erin missed over the weekend.
No description provided.